Player Variables
"Player Variables" store information about each active Player character. They store both
the Player's constants, and his actively changing data. There are four different types:
Main Constants - Constants required by the program, listed in this documentation
Custom Constants - Constants defined by the user by creating extra Player Constant
space with the appropriate option in the Game Def file, which
are listed below the "Main Constants" in the Character Def
Main Variables - Variables required by the program, listed in this documentation
Custom Variables - Variables defined by the user by creating extra Player Variable
space with the appropriate option in the Game Def file
When referencing them from a script, the Main Constants can be referenced by simply using
their ID number, such as "0" for "Character's Init Function", or with a preceding capital "C",
such as "C0". A lower-case "c" (such as "c0") should be used for referencing Custom Constants.
To reference an Active Variable, its ID number should be preceded by a capital "A" (such as
"A0" for "Player_Movement_Mode") for the variables listed in this documentation, or by
lower-case "a" for Custom Variables. If any variables must be referenced without using the
letter symbols, their IDs must be calculated in this manner:
(C) Main Constant = ID#
(c) Custom Constant = #_of_Main_Constants + ID#
(A) Main Variable = #_of_Main_Constants + #_of_Custom_Constants + ID#
(a) Custom Variable = #_of_Main_Constants + #_of_Custom_Constants + #_of_Main_Variables + ID#
When using the letter symbols, however, each different type is a list of its own, each
starting at index 0. This method helps compatibility in case the length of any of the
lists changes. All references not using the letter symbols must be updated any time a
list is lengthened or shortened by using the method described above
While the "Constants" are only for reference purposes (reading and testing), they can
be modified, however, recommended use is that Constants that represent values that must
change during play are copied to the active variable area, and used from there, so that
their original values remain in-tact. Modified constants may be reverted to their initial
values, however, by using the "_Player_RestoreConstants" Script Command
The Main Player Constants are loaded from the "Character Def" file, and because they
are described in detail in its documentation, listed here is simply an index:
0 - _Player_InitFunc
1 - _Player_VPScroll_Left
2 - _Player_VPScroll_Right
3 - _Player_VPScroll_Up
4 - _Player_VPScroll_Down
5 - _Player_VPX_Speed
6 - _Player_VPY_Speed
7 - _Player_SlopeTolerance_Floor
8 - _Player_SlopeTolerance_Ceiling
The Main Player Variables are as folows:
(To reference them, either put "A" directly in front of ther ID number, or add the total
number of Player constants that were loaded from the "Character Def" to its ID)
Variable Index:
0 - _Player_Type
1 - _Player_Movement_Mode
2 - _Player_Path_Mode
3 - _Player_X_Pos
4 - _Player_Y_Pos
5 - _Player_VPX
6 - _Player_VPY
7 - _Player_X_Vel
8 - _Player_Y_Vel
9 - _Player_Path_Vel
10 - _Player_Previous_X_Vel
11 - _Player_Previous_Y_Vel
12 - _Player_Previous_Path_Vel
13 - _Player_X_Count
14 - _Player_Y_Count
15 - _Player_Leftover_X_Count
16 - _Player_Leftover_Y_Count
17 - _Player_X_Dir
18 - _Player_Y_Dir
19 - _Player_Cant_Go_Up
20 - _Player_Cant_Go_Down
21 - _Player_Cant_Go_Left
22 - _Player_Cant_Go_Right
23 - _Player_Path_Angle
24 - _Player_Motion_Angle
25 - _Player_Collision_Angle
26 - _Player_On_Path
27 - _Player_Was_On_Path
28 - _Player_Solid_Plane
29 - _Player_Collision_Area
30 - _Player_InvertMirror
31 - _Player_InvertFlip
32 - _Player_Curr_Boundary
33 - _Player_Flash_Timer
34 - _Player_Freeze
35 - _Player_DebugNum
36 - _Player_Flags
37 - _Player_VP_XPan
38 - _Player_VP_YPan
Descriptions:
0 - _Player_Type
| This is the ID value of the character script that this active Player object is using. By recommended usage, this value should only be modified with the Set_Player_Character script command
|
1 - _Player_Movement_Mode
| This is the current scripted "Movement Mode" the Player is using, which controls how he interacts with the environment, and the effects of input
|
2 - _Player_Path_Mode
| This is the current hard-coded level collision "Path Mode" the Player is using, which controls in which direction the Player tests for level solidity for path tracing. If the Player is flagged
to follow a curved path, this value will change as he rounds a 45-degree angle while following a level path or a Tiled Path Object. The value may also be set directly by script commands, and will read or can be set to one of the following:
0 - _PPM_Floor
1 - _PPM_Right
2 - _PPM_Ceiling
3 - _PPM_Left
4 - (No Collision)
5 - (No Collision)
6 - (No Collision)
7 - (No Collision)
8 - _PPM_Debug
|
3 - _Player_X_Pos
4 - _Player_Y_Pos
| These are the current X and Y coordinates of the Player within the level.
|
5 - _Player_VPX
6 - _Player_VPY
| These are the current X and Y positions of the Player's "View Port" in the level. These
values will be updated automatically if the Player is flagged for "Automatic Viewport Update",
or the values may be set directly by script commands. These values are copied to the vp?r[?] Game Registers,
added with the Player_VP_?Pan offset values, and then clipped to the level boundaries.
The final product of this operation is used as the position at which to draw each of the visible Player screens
|
7 - _Player_X_Vel
8 - _Player_Y_Vel
9 - _Player_Path_Vel
|
These are the current X, Y, and Path velocities of the Player. "Path Velocity" is "vector",
or actual velocity. It is used to create X and Y velocity when attached to
a surface, based on the angle value at the point at which the Player is standing on a level path or Tiled Path Object.
When the Player is not connected to a path, or if the Player is flagged not to use vectored movement,
or not to follow a path, "Path Velocity" affects X and Y Velocities in the following way:
Floor: X = Path
Ceiling: X = -Path
LWall: Y = Path
RWall: Y = -Path |
10 - _Player_Previous_X_Vel
11 - _Player_Previous_Y_Vel
12 - _Player_Previous_Path_Vel
|
These values represent the X, Y, and Path velocities that the Player had at the start of the current game frame, and can be read in case
those velocities are required by a script function, as the current velocities are reset to 0 when the level or a solid
object are struck on the corresponding axis
|
13 - _Player_X_Count
14 - _Player_Y_Count
|
These values are used for fine-movement with non-whole-value velocities. For every 256 units of velocity, the Player will
move one pixel across the level. At the beginning of each Player's hard-coded movement phase, HCGE adds the X and Y
velocity values to these counters, and moves the Player by one pixel for every 256 units. Remaining units are left
in the counters at the end of movement, and added to the velocity when the object is moved again on the next game frame
to achieve more fluid movement
They normally shouldn't be modified by script, but can be read or modified
when circumstances warrant. Setting these values during Object Collision functions will change the distance
that the Player moves during that game frame, as the collision tests take place while the counters are being used to
move the Player
|
15 - _Player_Leftover_X_Count
16 - _Player_Leftover_Y_Count
|
These values are set by HCGE when the Player strikes a solid level plane or solid object during movement. They represent
the value remaining in the above-described "count" variables when the Player struck the solidity, meaning that this is
the amount of potential movement that the Player was not allowed to make during this game frame. They are reset at the
beginning of the Player's hard-coded movement phase each game frame
|
17 - _Player_X_Dir
18 - _Player_Y_Dir
19 - _Player_Cant_Go_Up
20 - _Player_Cant_Go_Down
21 - _Player_Cant_Go_Left
22 - _Player_Cant_Go_Right
|
These values represent whether or not the Player is obstructed by the Level or a Solid Object in any of these four directions.
If the Player is not obstructed, the value would be zero. If the Player is obstructed by the level, HCGE will set the
value equal to the ID number of the Tile Plane that the Player has collided with, meaning that a positive value is always a tile plane,
while Solid Objects are signified by a negative value, this value being a pointer to the object itself. For an Object to
be "solid", the Object's Scripted Collision Function must use the appropriate Script Commands to test for
a Player's collision with its MainBounds Box, and then use the Commands to set the appropriate "Cant_Go" value
equal to a pointer to the object
|
23 - _Player_Path_Angle
|
When a Player is following a path, this value is set equal to the angle that HCGE has obtained from the path at the point
of collision with the Player. This value is only updated while the Player is on a level path or tiled path object.
If the Player is in freespace, or is moving on top of a solid object, it remains unchanged until the Player strikes another path
|
24 - _Player_Motion_Angle
|
This value represents the angle at which the Player is actually moving, whether he is following a path or is in freespace
|
25 - _Player_Collision_Angle
|
When a Player strikes solidity during movement, this value is set equal to the angle obtained from the point of collision.
It is only meaningful during the game frame at which collision has occurred. At the beginning of the Player's hard-coded movement
during the next game frame, the value is set equal to 256, meaning that no collision has taken place. This value is affected
by striking a path while in freespace, but not by a path that is already being followed
|
26 - _Player_On_Path
|
This value represents whether or not the Player is standing on a path or solid object. The value is set by HCGE automatically
at the end of the Player's hard-coded movement for each game frame, being made equal to the appropriate Player_Cant_Go_???
variable that corresponds with the current Player_Path_Mode setting, and is used to determine what the Player
is standing on as a "path", rather than what he is colliding with in any specific direction
|
27 - _Player_Was_On_Path
|
At the beginning of the Player's hard-coded movement for each game frame, HCGE sets this value equal to the value of the above-described
"Player_On_Path" variable before it is modified. Testing this value allows scripts to determine exactly when the Player connects to or
disconnects from a "path"
|
28 - _Player_Solid_Plane
|
Before the Player is allowed to move, this value must be set by script to be equal to the ID number of the tile plane that
the Player should test for collisions with. The value can be changed mid-gameplay to cause the Player to take alternate paths. If the
Player's X/Y coordinates move beyond the size of the tile plane, the coordinates at which the Player tests for collision will be
wrapped-around to the opposite side, preventing game crashes, and allowing proper collision with looped levels
|
29 - _Player_Collision_Area
|
This value reflects which of the 9 collision areas the Player is being tested for
object collision in during the collision testing phase while level looping is active. It is set by HCGE and is meant for read only,
as altering it manually will cause collisions to be missed if set between 0 and 8,
or cause a crash if set to any other value
|
30 - _Player_InvertMirror
31 - _Player_InvertFlip
|
These values reverse the meaning of the Player_?_Dir variables. Valid settings are 0 for normal, and 1 for reverse
|
32 - _Player_Curr_Boundary
|
This value reflects the ID number of the last "Boundary Event" that was triggered by this Player, used
to ensure that the event is only triggered once when the Player or his camera first enters the boundary range. It is
set by HCGE when the Player enters the boundary, but may be set by script to prevent an event from triggering, or to
re-trigger an event
|
33 - _Player_Flash_Timer
|
This value is used to flicker the Player, as in situations such as being invulnerable after taking damage. The Player
is only drawn when this value is divisible by 4. It is the responsibility of the game scripts to set and manage this
value, as it is otherwise meaningless to HCGE
|
34 - _Player_Freeze
|
This value is used to freeze the Player in place. Valid settings are:
| 0 | - | _PFreeze_Off | - | Player is allowed to move and update |
| 1 | - | _PFreeze_Movement | - | Player isn't allowed to move, but still processes his update phase |
| 2 | - | _PFreeze_All | - | Player isn't allowed to move or update |
|
35 - _Player_DebugNum
|
This value determines which entry in the current zone's debug listing to use for object display and
placement when the Player is in debug mode. It must be set by script, and must not be set below 0,
or in excess of the size of the debug list for the current zone
|
36 - _Player_Flags
|
This value acts as a bitfield whose flags determine how HCGE handles the Player's movement and interaction with the
level, and must be set by script before the level starts, or during gameplay, as the situation warrants. The flags represented by
this value are as follows:
| 0 | - | _PFlag_UpperBound | - | The upper level boundary acts as solid |
| 1 | - | _PFlag_LowerBound | - | The lower level boundary acts as solid |
| 2 | - | _PFlag_LeftBound | - | The left level boundary acts as solid |
| 3 | - | _PFlag_RightBound | - | The right level boundary acts as solid |
| 4 | - | _PFlag_VPCenter | - | HCGE centers the viewport around the Player using his automatic viewport settings |
| 5 | - | _PFlag_SolidFriction | - | When the Player strikes solidity on one axis, his remaining velocity on the opposite axis is ignored during this game frame |
| 6 | - | _PFlag_FollowPath | - | The Player will attach to and follow paths in the direction of his currently-set Path Mode |
| 7 | - | _PFlag_WallCollision | - | Player tests for collision with "walls" (solidity perpendicular to his "path mode") along the full length of his MainBounds, rather than only at his centerpoint |
| 8 | - | _PFlag_UseVector | - | Player uses Path Angle and Path Velocity to determine the actual X/Y velocity at which to move |
| 9 | - | _PFlag_FollowCurves | - | Player automatically changes Path Mode upon reaching a 45-degree angle to follow a curved path |
| 10 | - | _PFlag_RotateBounds | - | The "MainBounds" assigned to the Player that are used for level collision testing are rotated 90-degrees when the Player is using a "wall" Path Mode for a more circular effect than rectangular |
|
37 - _Player_VP_XPan
38 - _Player_VP_YPan
|
These values can be used to "pan" the viewport during gameplay for any reason. They are added to the
Player_VP? settings by HCGE when they are being applied to the vp?r[?] Game Registers
to set the drawn screen position for each Player
|